Links to issues

Closes #84.

Description

Adds the authorisation foundation that the rest of the milestone
work builds on:

• App\Security\Roles — constants ROLE_USER,
  ROLE_DOMAIN_MANAGER, ROLE_ADMIN so controllers, voters, and
  templates stop typing the raw strings.
• role_hierarchy in security.yaml: ROLE_ADMIN implies
  ROLE_DOMAIN_MANAGER. One admin surface serves both site-wide
  admins and domain-scoped approvers.
• App\Security\EmailDomain::of(User): ?string — pure helper that
  extracts the lowercased part after @. Defensive: returns null
  for missing email, missing @, or trailing @. Reused by the
  voter today and by the scoped user-management repository finder in
  the upcoming feat: scoped user-management list view for admins and domain managers #85.
• App\Security\Voter\ManageUserVoter — supports the attributes
  MANAGE_USER, APPROVE_USER, BLOCK_USER against a User
  subject. Grants when the actor (a) holds ROLE_DOMAIN_MANAGER,
  (b) is ROLE_ADMIN (short-circuit across every domain), or
  (c) shares the lowercased email domain with the subject. The voter
  never reads status — identity state stays orthogonal to
  authorisation.

No existing tests modified — the
PR adds two new test files
(tests/Unit/Security/Voter/ManageUserVoterTest.php,
tests/Unit/Security/EmailDomainTest.php).

Screenshot of the result

n/a — security plumbing, no UI.

Checklist

• My code is covered by test cases.
• My code passes our test (all our tests).
• My code passes our static analysis suite.
• My code passes our continuous integration process.

Verified locally:

• task coding-standards-check — PHP CS Fixer, Twig CS Fixer,
  Prettier (YAML / JS / CSS), markdownlint, composer validate +
  normalize — all green.
• task test-coverage — 63 tests, 187 assertions, 100 %
  coverage.

Additional comments or questions

Symfony\Component\Security\Core\Authorization\Voter\Voter's
voteOnAttribute() signature in Symfony 8 carries an optional
fourth ?Vote $vote = null argument; the override matches that
exact signature. The Vote slot is unused here (we always answer
with a bool) — Symfony's vote-explanation feature is opt-in and
unrelated to ADR 006's decision flow.

Voter uses AccessDecisionManagerInterface::decide() rather than
inspecting User::getRoles() directly so that the configured
role_hierarchy applies — ROLE_ADMIN implying
ROLE_DOMAIN_MANAGER is what makes the admin short-circuit work
without two role assignments on the actor's user row.

Details - AI specificities

• ADR: docs/adr/006-user-approval-and-account-state.md
  (Draft; lands via docs: add ADR 004 — user registration, approval, and account state #61). Specifically the "Domain manager — a
  role, not a flag" section: ADR 006 deliberately models the
  per-domain approver capability as a role on the existing
  User.roles column rather than a dedicated boolean. Scope (which
  domain the manager governs) is derived from the user's own email
  rather than a relation.
• Independent of PR 1 (feat(user): add name and status fields per ADR 006 (#45, #83) #86). This PR doesn't touch any of the
  fields PR 1 adds (name, status) and doesn't change the User
  constructor signature. The voter reads getEmail() and getRoles()
  which exist on develop today.
• Reused downstream:
  • EmailDomain::of() is consumed again by UserRepository::findVisibleTo()
    in PR 5 (feat: scoped user-management list view for admins and domain managers #85).
  • The voter is invoked by IsGranted('MANAGE_USER', subject: $user)
    on the approval / block / list actions in PR 5 (feat: approval queue for domain managers #64 + feat: scoped user-management list view for admins and domain managers #85).
• Out of scope:
  • Any access-control rule for the admin user-management surface
    (/admin/users) — added in PR 5 (feat: scoped user-management list view for admins and domain managers #85).
  • UI to assign / revoke ROLE_DOMAIN_MANAGER — separate concern,
    not currently tracked as an issue.
  • The Domain entity. The ADR is explicit: only introduce one if
    an organisation later needs to span multiple email domains or a
    user must manage a domain other than their own email's. Don't
    pre-build the relation.
• Test design. Unit-only via AccessDecisionManagerInterface
  mocks. A functional voter-on-controller test belongs in PR 5,
  where the voter is actually invoked from a route.